/***************************************************************
 *  Copyright (c) 2007 by GroupMe! Team (www.groupme.net)
 *  All rights reserved
 *
 *  This file is part of the GroupMe! Project. You can utilize
 *  software of the GroupMe! project under the terms of the 
 *  GNU Lesser General Public License as published by the
 *  Free Software Foundation in version 2.1.
 * 
 *  The GNU Lesser General Public License can be found at:
 *  http://www.gnu.org/licenses/lgpl.html
 *
 *  This copyright notice MUST APPEAR in all copies of the file!
 ***************************************************************/
package net.groupme.model;

import java.net.URL;
import java.util.Collection;

import net.groupme.exceptions.DeleteFailedException;
import net.groupme.exceptions.IDNotFoundException;
import net.groupme.exceptions.InsertFailedException;
import net.groupme.exceptions.UpdateFailedException;
import net.groupme.model.rdf.Statement;

/**
 * This inteface defines a Resource object in the GroupMe! project. Resources
 * can be combined to a Group {@link net.groupme.model.Group}. A Resource can
 * be a single thing (image, video, text, feed etc.) or a Group. It can be
 * tagged and has an URL.
 * 
 * @author Mischa Frank <a
 *         href="mailto:code@planetfrank.net">code@planetfrank.net</a>
 * @author Patrick Siehndel <a
 *         href="mailto:patrick.siehndel@gmx.de">patrick.siehndel@gmx.de</a>
 * 
 * created on 12.11.2006 <br/>
 * 
 * @version 0.1
 * 
 */
public interface Resource extends Identifiable {

	/**
	 * This method creates a new {@link Statement} and adds it to the Statements 
	 * of the Resource. The Subject of the Statement is the Resource itself.
	 * @param property the property (full URI)
	 * @param object the Object of the Statement
	 * @param datatype the datatype of the Object
	 * @throws InsertFailedException 
	 * @throws IDNotFoundException 
	 */
	public void addStatement(String property, String object, String datatype) throws IDNotFoundException, InsertFailedException;

	/**
	 * This method adds a Tag to the Resource by a given User.
	 * 
	 * @param tagger/user
	 *            who tagged tge Resource
	 * @param tag
	 * @throws InsertFailedException
	 */
	public void addTag(User tagger, Tag tag) throws InsertFailedException;

	/**
	 * This method adds a Tag to the Resource by a given User for a given Group.
	 * 
	 * @param tagger/user
	 *            who tagged tge Resource
	 * @param tag
	 * @param group
	 * @throws InsertFailedException
	 */
	public void addTag(User tagger, Tag tag, Group group)
			throws InsertFailedException;

	/**
	 * This method adds a Tag to the Resource by a given User for a given Group
	 * with an importance.
	 * 
	 * @param tagger/user
	 *            who tagged tge Resource
	 * @param tag
	 * @param group
	 * @param importance
	 * @throws InsertFailedException
	 */
	public void addTag(User tagger, Tag tag, Group group, Double importance)
			throws InsertFailedException;

	/*
	 * (non-Javadoc)
	 * 
	 * @see net.groupme.model.Identifiable#getDescription()
	 */
	public String getDescription();

	/**
	 * This method returns the name of the Resource.
	 * 
	 * @return name of the Resource
	 */
	public String getName();

	
	/**
	 * This method returns the Date the resource was created
	 * 
	 * @return the Date the Resource was created
	 */
	public String getDateCreated();
	
	
	/**
	 * This method returns all {@link Statement} associated with the Resource.
	 * @return a Collection of Statements
	 */
	public Collection<Statement> getStatements();

	/**
	 * This method returns all Tags the Resource has.
	 * 
	 * @return Collection of Tags the Resource has
	 */
	public Collection<Tag> getTags();

	/**
	 * This method returns all Tags which the Resource has in a given Group.
	 * 
	 * @return Collection of Tags the Resource has in a Group
	 */
	public Collection<Tag> getTags(Group group);

	/**
	 * This method returns all Tags a given User tagged to the Resource.
	 * 
	 * @return Collection of Tags the Resource got from a given User
	 */
	public Collection<Tag> getTags(User tagger);

	/**
	 * This method returns all Tags a given User tagged to the Resource for a
	 * given Group.
	 * 
	 * @return Collection of Tags the Resource got from a User in a Group
	 */
	public Collection<Tag> getTags(User tagger, Group group);

	/**
	 * This method returns the type of the Resource.
	 * 
	 * @return type of the Resource
	 */
	public String getType();

	/**
	 * This method returns the URL of the Resource.
	 * 
	 * @return URL of the Resource
	 */
	public URL getURL();

	/**
	 * This method removes a {@link Statement} from the Resource.
	 * @throws DeleteFailedException 
	 */
	public void removeStatement(Statement statement) throws DeleteFailedException;

	/**
	 * This method removes a Tag from Resource.
	 * 
	 * @param tagger/user
	 *            who tagged tge Resource
	 * @param tag
	 * @param group
	 * @throws DeleteFailedException
	 */
	public void removeTag(User tagger, Tag tag, Group group)
			throws DeleteFailedException;
	
	/**
	 * This method sets the name of the Resource.
	 * 
	 * @param name
	 * @throws UpdateFailedException
	 */
	public void setName(String name) throws UpdateFailedException;
	
	/**
	 * This method sets the type of the Resource.
	 * 
	 * @param Type
	 * @throws UpdateFailedException
	 */
	public void setType(String type) throws UpdateFailedException;
	
	/**
	 * This method sets the URL of the Resource.
	 * 
	 * @param URL
	 * @throws UpdateFailedException
	 */
	public void setURL(URL url) throws UpdateFailedException;
	
	/** 
	 * This method returns the collection of groups the resource is involved in. 
	 * @return collection of groups the resource is involved in
	 */
	public Collection<Group> getGroups();
}